Project State & Key Data Structures
The system is a single-page browser app (index.html + five JS modules) that trains UPS package sorters on routing decisions. The core data structures underlying all mathematical analysis are:
| Symbol | Code name | Description |
|---|---|---|
| $Z$ | TRUTH_RAW → _tmap | Set of ~41,000 ZIP codes with routing |
| $B$ | BELT_NAMES indices 0–15 | 16 belt destinations |
| $f$ | _tmap : Map<zip, entry> | The routing function |
| $\mathcal{F}$ | BELT_FAMILIES | Confusion neighbourhood graph |
| $\mathcal{E}$ | sort_events store | Sequence of sorter answer events |
| $\mathcal{O}$ | overlays store | Finite set of routing corrections |
| $w$ | _cfg.stateWeights | State weight vector |
| $M$ | computed in missortMatrix() | The missort count matrix |
Belt index reference (canonical, corrected 2026-05-13):
*PD-13/Middle Blue (index 12): peak season overflow only. CCHIL belts: {3, 4, 8}. Air belts: {13, 14}.
The OJS-to-LTC Certification Chain
0.1 What OJS Certifies
The LTC system does not operate in isolation. It is the knowledge layer in a two-layer employee certification architecture; the method layer beneath it is the On-Job Supervision system (GEMS #1760). Four role-specific OJS certification sheets exist:
| Sheet | Role | Total Methods | Nature of Certification |
|---|---|---|---|
| unloader-ojs | Metro Unloader | 127 | Equipment setup, package selection, unload sequence, flow management |
| sorter-ojs | Sort aisle sorter | 111 | Presort, label reading, body position, package routing to color-coded belts |
| pickoff-ojs | Pick-off employee | 87 | Chute routing, belt flow management, loader coordination |
| loader-ojs | Loader (Load SMART Scanning) | 168 | Scanner setup, ULD bay-scan, package scanning, wall building, smalls handling |
Each method must be explained (E) with a benefit or consequence in the trainee's own words, and demonstrated (D) at production rate. Passing threshold: 95% or higher. Recertification: every six months.
0.2 How OJS and LTC Differ
The two certifications address orthogonal dimensions of competency. OJS certifies how to execute the role: correct body position, hand-to-surface handling, scanner setup, ULD bay-scan sequence, "scan one, load one" cadence. LTC certifies where: SLIC-to-belt routing for sorters, ZIP exception routing for pick-offs, scan attribution discipline for loaders.
An employee with full OJS but incomplete LTC routing knowledge executes the correct physical method while making routing errors — producing missorts (sorters) or misloads (pick-offs). An employee with complete LTC routing knowledge but degraded OJS method compliance may know the correct destination but execute the scanning sequence in ways that corrupt iGate attribution (e.g., skipping Method #20 — the bay-door ULD scan — or using a coworker's ID in violation of Method #7).
0.3 Implication for the Sorter Channel Model
Section 5 models the sorter as a discrete memoryless channel with transition matrix $\mathbf{M}$. Departures from the identity $\mathbf{I}_{16}$ arise from two distinct sources the channel model does not currently separate:
- Knowledge gaps (LTC layer): the sorter does not know the correct belt for a given ZIP/SLIC. This is what LTC quiz accuracy measures.
- Method gaps (OJS layer): the sorter knows the correct belt but reads the label incorrectly (label facing wrong, fatigue-degraded pattern recognition). These produce errors even at full routing knowledge.
Partition the confusion matrix $\mathbf{M}$ into a knowledge-gap component $\mathbf{M}_K$ and a method-gap component $\mathbf{M}_E$ such that $\mathbf{M} = \mathbf{M}_K \cdot \mathbf{M}_E$. LTC directly reduces $\mathbf{M}_K \to \mathbf{I}$; OJS recertification reduces $\mathbf{M}_E \to \mathbf{I}$. Both are needed for $\mathbf{M} \to \mathbf{I}$.
The Routing Function
1.1 Basic Structure
Let $Z \subset \{0, \ldots, 99999\}$ be the set of ZIP codes with defined routes, $|Z| \approx 41{,}000$. Let $B = \{0, 1, \ldots, 15\}$ be the belt index set. The routing function is:
This is a total function on its domain (every loaded ZIP maps to exactly one belt), but a partial function over all possible 5-digit strings $\{00000, \ldots, 99999\}$. The pair $(Z, B, f)$ constitutes a finite relational structure — specifically a functional binary relation (each $z \in Z$ has exactly one image under $f$).
1.2 The CCHIL Multivalued Extension
For ZIPs in the 13 CCHIL states (MS, IA, WI, MN, SD, ND, NE, LA, OK, CO, WY, AZ, NM), the app accepts any of the three CCHIL belts as correct. The routing becomes a multifunction:
The sorter's answer $a \in B$ is marked correct iff $a \in \tilde{f}(z)$. This is equivalent to defining an acceptance relation $\mathcal{A} \subseteq Z \times B$ where $(z, b) \in \mathcal{A}$ iff $b \in \tilde{f}(z)$.
1.3 Properties
$f$ is not injective in general: many ZIPs in different states share a belt destination. $f$ is not surjective over $B$ from every state. The preimage partition $\{f^{-1}(b) : b \in B\}$ is a partition of $Z$ into 16 classes — this partition is the fundamental structure the sorter must learn.
Characterise the preimage sizes $|f^{-1}(b)|$ for each belt $b$. Belts with large preimages are easier to learn by frequency; belts with small preimages are easily missed and dominate the Missort Matrix.
The ZIP Code Space as an Ultrametric
2.1 Prefix Metric
ZIP codes viewed as 5-character strings admit a natural prefix metric. Define the longest common prefix length $\ell(z_1, z_2) = \max\{k : z_1[1..k] = z_2[1..k]\}$ and the metric:
(with $d(z,z)=0$). This satisfies the ultrametric inequality:
which is strictly stronger than the triangle inequality. The set $(Z_{\text{all}}, d)$ is therefore an ultrametric space. Ultrametric spaces are "tree-like" — the metric corresponds to depth of divergence in the ZIP prefix trie, which matches physical geography: nearby ZIP codes share longer prefixes and route to the same or related belts.
2.2 Local Constancy of the Routing Function
Empirically, $f$ is locally constant at the 3-digit prefix level:
Formally, $f$ approximately factors through the quotient map $\pi : Z \to Z/{\sim_3}$ where $z_1 \sim_3 z_2 \iff z_1[1..3] = z_2[1..3]$, giving $f \approx \bar{f} \circ \pi$ where $\bar{f} : Z/{\sim_3} \to B$ is the prefix routing function. The ~800 active 3-digit prefixes cover all 41,000 ZIP entries.
Quantify the exceptions to local constancy — ZIPs within the same 3-digit block routing to different belts. These are the cases where the sort chart has sub-prefix distinctions and are prime candidates for sorter confusion.
The Belt Confusion Graph
3.1 Definition
Define the confusion graph $G = (B, E)$ as a directed graph on the 16 belt nodes, where $(b_i, b_j) \in E \iff b_j \in \texttt{BELT\_FAMILIES}[b_i]$. The graph encodes domain knowledge about which belts are physically or visually similar.
Top Red (8) confuses with Top Blue (11) — sister belts in the Z3 area (PD-09/PD-12): same physical quadrant, different colour. Middle Red (7) and Middle Blue (12) form the PD-08/PD-13 sister pair — high confusion because PD-13 appears only during peak season, making it unfamiliar even to experienced sorters returning after non-peak rotation.
3.2 Role in the Quiz Engine
When generating a wrong-answer distractor set, the quiz selects answers from $\mathcal{F}(b^*) = \{b : (b^*, b) \in E\}$ — the out-neighbourhood of the correct belt. This ensures distractors are semantically hard, not random. From a learning theory perspective, this is related to hard negative mining: training on confusable pairs accelerates discriminative learning compared to random negatives.
3.3 Graph-Theoretic Properties
BELT_FAMILIES is not symmetric in general, so $G$ is a directed graph. Define confusion classes as weakly connected components. From the belt naming, the natural colour families are: Black {0, 15}, Blue {11, 12}, Red {8, 7, 4}, Green {6, 13, 14}, Yellow {1, 3, 10}, White {2, 5}, Air {13, 14}, Orange {9} (singleton).
Compute the chromatic number of the undirected version of $G$. A $k$-colouring assigns each belt a "colour class" such that confusable belts get different colours — the minimum number of visually distinguishable categories needed to make belt identification unambiguous.
Weighted Question Selection as a Mixture Distribution
4.1 The Four-Pool Model
The quiz generates questions from four pools — Ground ($P_g$), CCHIL ($P_c$), Exception labels ($P_e$), and Air sort ($P_a$) — where the average per-state contribution $\bar{n}$ normalises all special pools:
The question type is selected by sampling uniformly from the total pool, giving a categorical mixture distribution over question types:
4.2 The Pre-v0.14 Bug and Its Fix
Before v0.14, air and exception bucket sizes were computed as $|\text{candidates}| \times w$ (e.g., $7 \times 20 = 140$) while the ground pool was ~33,000 — giving an air share of $140/33{,}140 \approx 0.4\%$, negligible at any weight. The fix: replace the raw count with $w \times \bar{n}$, making all pools commensurate. With $w_a = 3$ and $\bar{n} \approx 868$: $P_a = 3 \times 868 = 2604$, giving $\Pr[\text{air}] \approx 7.4\%$. The fix is equivalent to converting heterogeneous measures to a common denominator before mixing — the mixture distribution becomes well-calibrated with respect to the weight sliders.
4.3 The CCHIL Isolation Fix (v0.12)
Before v0.12, CCHIL states were included in the ground pool weighted by $w_s \times |G_s|$, causing their aggregate contribution to dominate. The fix isolates CCHIL into its own pool with a single weight $w_c$, imposing independence of CCHIL frequency from regional weight adjustments — making the CCHIL component orthogonal to regional adjustments in the mixture.
The Missort Matrix as a Discrete Communication Channel
5.1 Channel Model
A sorter can be modelled as a discrete memoryless channel with input and output alphabet $B$. The channel transition matrix is:
$\mathbf{M}$ is a right stochastic matrix: each row sums to 1. A perfect sorter has $\mathbf{M} = \mathbf{I}_{16}$. A random guesser has $M_{ij} = 1/16$ for all $i, j$. The diagonal $M_{ii}$ is per-belt accuracy; off-diagonal $M_{ij}$ are missort rates.
5.2 Information-Theoretic Measures
Per-belt Shannon entropy of the sorter's output distribution (the $i$-th row of $\mathbf{M}$):
The mutual information between correct belt $X$ and chosen belt $Y$:
$I(X;Y)$ measures how much the sorter's answer reveals about the correct belt. For a perfect sorter, $I(X;Y) = H(X)$ (full information). For a random guesser, $I(X;Y) = 0$. Channel capacity $C = \max_{p(X)} I(X;Y)$ bits per question.
Add an entropy column to the belt analysis tab showing $H_i$ per belt. High-entropy belts are a priority for coaching regardless of absolute accuracy, because entropy captures systematic confusion (wrong internal model), whereas low accuracy on a low-entropy belt may just mean the sorter doesn't know it — a simpler training problem.
Sorter Performance as a Statistical Process
6.1 Bernoulli Trials Model
Each quiz question for sorter $k$ is modelled as a Bernoulli trial with success probability $\theta_k \in [0,1]$. The MLE of $\theta_k$ is the sample accuracy: $\hat{\theta}_k = \text{correct}/n$.
6.2 Confidence Intervals
The Wald interval behaves poorly for small $n$. The Wilson score interval is preferred:
with $z = 1.96$ for 95% confidence. This interval has correct coverage for all $n$ and all $\theta$, including $\theta$ near 0 or 1. A sorter with 5/5 correct ($\hat{\theta} = 100\%$) has a Wilson interval of $[0.54, 1.00]$ — the data are entirely consistent with a true skill of 54%.
Add Wilson lower-bound sorting as an alternative ranking mode — rank sorters by the lower endpoint of their Wilson interval rather than $\hat{\theta}$. This corrects for the optimism bias that makes new sorters with 3/3 appear above experienced sorters with 120/150.
6.3 Trend Detection: Half-Split Test
The proper statistical test for non-stationarity is a two-sample proportions test:
under $H_0: \theta_{\text{early}} = \theta_{\text{late}}$, where $\hat{\theta}$ is the pooled accuracy.
Implement the formal two-proportions $z$-test and display a $p$-value alongside the trend arrow. A threshold like $p < 0.05$ gives statistical confidence that the apparent trend is real rather than noise.
6.4 Session-Level Trend: A CUSUM Perspective
The sparkline chart can be interpreted as a CUSUM (cumulative sum control chart): if we define $S_n = \sum_{t=1}^{n}(X_t - \theta_0)$ for some target accuracy $\theta_0$, then $S_n > h$ signals that the process has shifted above $\theta_0$. CUSUM is standard in industrial quality control — exactly the setting in which this system operates.
The Analytics Reducers as Monoid Homomorphisms
7.1 Algebraic Setup
Let $\mathcal{E}^*$ be the set of all finite sequences of sort events, with concatenation $(\cdot)$ as the binary operation and the empty sequence $\varepsilon$ as the identity. Then $(\mathcal{E}^*, \cdot, \varepsilon)$ is the free monoid over the event type $\mathcal{E}$.
Each analytics function that maps events to additive summary statistics is a monoid homomorphism: $(\mathcal{E}^*, \cdot, \varepsilon) \to (\text{Stats}, \oplus, 0)$. For example:
7.2 Why This Matters
The monoid structure implies the computation can be parallelised via MapReduce: partition the event log into chunks, reduce each chunk independently, then merge. This is the mathematical reason the analytics module is architected as pure reducers — the "no side effects in computation functions" design note is a structural requirement for the monoid homomorphism property to hold. Practically, incremental computation becomes possible: store partial aggregates and update only the new events.
7.3 Functions That Are Not Monoid Homomorphisms
worstBelt, worstSorter — these involve sorting and filtering, which are non-linear operations on the merged stats. missortMatrix — the matrix itself is a homomorphic aggregate, but rendering top confusion pairs involves a sort, making the render step non-homomorphic. The pattern is: (1) compute the aggregate homomorphically, (2) apply a non-linear query to the aggregate — analogous to SQL's GROUP BY (homomorphic) vs ORDER BY / HAVING (not).
The Overlay System as a Pointed Function Update
8.1 Algebraic Formulation
An overlay is a finite partial function $o : D_o \to B$ where $D_o \subset Z$. The overlay application operator $\triangleleft$ produces:
This is the pointwise override — $o$ takes precedence at its domain. In the category of sets and partial functions, $f \triangleleft o$ is a pushout.
8.2 Composability and Audit Trail
Multiple overlays $o_1, o_2, \ldots, o_k$ applied sequentially: $f' = f \triangleleft o_1 \triangleleft o_2 \triangleleft \cdots \triangleleft o_k$. The operation $\triangleleft$ is not commutative in general (later overlays override earlier ones on shared domains). The set of all finite partial functions $D \to B$ with $\triangleleft$ forms a left-regular band — an idempotent semigroup where $a \triangleleft a = a$ and $a \triangleleft b \triangleleft a = a \triangleleft b$. Associativity holds. The append-only log (overlays.jsonl) preserves the exact sequence of overrides — the history is auditable.
The Knowledge Map as a Linear Functional
9.1 Event Space and Filters
A filter $\varphi : \mathcal{E} \to \{0,1\}$ selects a subset of events. The sorter accuracy under filter $\varphi$ for sorter $k$ is:
This is a rational linear functional on the indicator function space — a ratio of two linear functionals (numerator and denominator are both linear in $\varphi$).
9.2 Filter Combinations as Set Operations
The combined filter $\varphi_{S, \text{CCHIL}, \text{air}}$ is the logical OR (union) of event subsets. The filter algebra is the Boolean algebra $\mathcal{P}(\mathcal{E})$ under union, intersection, and complement — the Knowledge Map explores a slice of this algebra indexed by the state/category selectors.
Implement intersection filters: "sorters who are strong in CCHIL and Air" — selects events matching both criteria, or evaluates sorter accuracy separately per category and ranks by the minimum (weakest category). Identifies sorters with balanced, broad knowledge versus specialists.
The Sort Chart as a Finite Automaton
The truth table was derived from a Sort Charts Master spreadsheet mapping ZIP → SLIC → Belt. This pipeline defines a two-step composed function:
Viewing the routing lookup as a decision process, the 3-digit ZIP prefix determines the SLIC, and the SLIC determines the belt. This is a deterministic finite transducer. The "truth edits" system (truth_edits.jsonl) applies state-transition overrides — rewriting individual arcs in the transducer without rebuilding the whole automaton.
The Probabilistic Skill Model (Bayesian Extension)
11.1 Beta-Bernoulli Model
A natural Bayesian model treats each sorter's true accuracy $\theta_k$ as a random variable with a Beta prior:
With a uniform prior $(\alpha = \beta = 1)$, the posterior mean is the Laplace-smoothed accuracy:
This shrinks extreme estimates towards 0.5, appropriate for small $n$.
11.2 Hierarchical Model for Belt-Specific Skill
A sorter's skill is not uniform across belts. A hierarchical Bayesian model would parameterise global sorter skill $\theta_k \sim \text{Beta}(\alpha_0, \beta_0)$ and per-belt skill $\theta_{k,b} \sim \text{Beta}(\alpha(\theta_k), \beta(\theta_k))$. The belt-specific posterior enables more precise coaching: a sorter globally proficient but with 60% accuracy on Top Blue (PD-12) likely has sister-belt confusion with Top Red (PD-09) — targeted intervention, not general retraining.
Formalise the Beta-Bernoulli model per belt per sorter and evaluate whether it changes coaching recommendations in practice. Each sorter has a latent skill vector $(\theta_{k,s})_{s \in \text{States}}$ indexed by state — a proper ranking should account for uncertainty using Wilson CI as a frequentist approximation.
Summary Table of Mathematical Structures
| Component | Mathematical Object | Key Property |
|---|---|---|
| ZIP-to-belt mapping | Partial function $f : Z \to B$ | Locally constant at 3-digit prefix |
| CCHIL routing | Multifunction $\tilde{f} : Z \to \mathcal{P}(B)$ | Acceptance relation, set-valued |
| ZIP code space | Ultrametric space $(Z, d)$ | $d(x,z) \leq \max(d(x,y), d(y,z))$ |
| Belt set with confusion | Directed graph $G = (B, E)$ | Encodes hard-negative structure |
| Question selection | Categorical mixture distribution | 4-pool weighted sampling |
| Sorter channel | Right stochastic matrix $\mathbf{M}$ | Perfect sorter $\Rightarrow \mathbf{M} = \mathbf{I}$ |
| Accuracy | Binomial proportion $\hat{\theta}$ | Wilson CI for uncertainty |
| Trend | Two-proportions test | Formal non-stationarity check |
| Overlay system | Pointed function update $f \triangleleft o$ | Left-regular band |
| Analytics reducers | Monoid homomorphisms $\mathcal{E}^* \to \text{Stats}$ | Enables MapReduce |
| Knowledge map filter | Boolean algebra $\mathcal{P}(\mathcal{E})$ | OR-composition of state indicators |
| Sorter skill | Beta-Bernoulli posterior | Bayesian shrinkage for small $n$ |
| Pipeline composition | Finite transducer $g \circ h$ | Two-step ZIP → SLIC → Belt |
Open Problems & Future Sessions
End of Session 2. Next session: pick up any [OPEN] item, or extend the framework with new mathematical connections discovered during implementation. Read Session Log before resuming.