AllocAI: Risk-Calibrated Capital Allocation for Logistics Networks#

A technical white paper

Abstract#

Capital allocation in logistics is a coupled forecasting-and-decision problem. Demand moves across a network, shocks propagate between modes and regions, and the best forecast is not automatically the best portfolio. AllocAI addresses that gap with AllocFormer-GTQ v0.1: a custom global single-target robust residual regression shared across panel rows, an evaluated but disabled relational context candidate, split-conformal calibration, a scenario-conditioned risk head, and a box-constrained quadratic optimizer with a linear downside/CVaR proxy. The validation gate disabled relational pooling in the shipped artifact; that block remains an evaluated model-family option, not a claimed source of v0.1 lift. The pilot is trained and evaluated chronologically on U.S. Bureau of Transportation Statistics Freight Analysis Framework (FAF) 5.7.1 annual origin–destination flows and uses the BTS Supply Chain and Freight Indicators dataset as exogenous context. It serves deterministic, constrained allocations through a portable API that builds as either a Cloudflare-compatible Worker or a standalone Node.js container, and it exposes the decision surface in a responsive WebGL interface.

The design incorporates current research ideas in robust temporal learning, relational forecasting, calibrated uncertainty, and downside-aware constrained optimization. The implementation is original, inspectable, and portable. This paper distinguishes empirical results backed by checked-in benchmark artifacts from supplemental scenario and engineering checks, separates factual dataset claims from modeled business metrics, documents limitations, and defines a path from public-data evaluation to an institution-grade model trained on company-specific cash flows and constraints.

Table of Contents#

1. Introduction & Motivation
2. Design Goals, Constraints & Anti-Goals
3. System Architecture
4. Data Model & Provenance
5. Forecasting Architecture
6. Risk-Aware Allocation
7. Serving & Product Interface
8. Determinism & Reproducibility
9. Interpretability & Confidence
10. API Surface
11. Performance Evaluation
12. Correctness & Quality Assurance
13. Licensing & Data-Governance Posture
14. Comparison to Prior Art
15. Limitations & Future Work
16. Conclusion
17. Appendices

• References

1. Introduction & Motivation#

1.1 The capital-allocation problem#

Logistics investors allocate capital across assets whose economics are connected: fleet capacity changes warehouse utilization; port congestion changes intermodal demand; fuel prices alter mode economics; automation changes service levels and labor exposure. Treating these opportunities as independent rows in a spreadsheet suppresses the most important feature of the domain: the network.

The decision also has two layers. First, a model must estimate the distribution of future freight activity, not merely a point forecast. Second, an optimizer must translate those estimates into a feasible portfolio under a finite budget, downside tolerance, concentration bounds, and strategic objectives. A forecasting leaderboard alone does not solve the allocation problem.

1.2 The opportunity#

Public logistics data have become sufficiently rich to support a credible pilot-training and benchmarking layer. FAF provides U.S. freight value, tonnage, and ton-miles by origin, destination, commodity, trade type, distance band, and mode. BTS publishes higher-frequency supply-chain indicators covering ports, rail, trucking, labor, capacity, and costs. The World Bank Logistics Performance Index is an intermittently observed, survey-based country indicator licensed CC BY 4.0, while OpenStreetMap provides an open road and facility graph subject to ODbL obligations. Neither expansion source is part of the reported v0.1 benchmark. Public sources cannot replace proprietary operating and financial data, but they provide useful structural priors and a transparent evaluation substrate.

1.3 The core idea: forecast a network, allocate a budget#

AllocAI couples four stages:

1. Provenance-aware ingestion converts open freight and macro data into chronological, leakage-resistant features.
2. Robust residual prediction with a validation-gated relational block estimates forward freight opportunity; the shipped artifact uses only feature groups that passed the predeclared validation gate.
3. Split-conformal calibration and a scenario-conditioned risk head convert chronological residual evidence and scenario inputs into bounded uncertainty and downside terms.
4. Box-constrained mean–CVaR-proxy quadratic allocation balances growth, resilience, and decarbonization while conserving capital and penalizing concentration and modeled downside risk.

The same inputs always produce the same output at a fixed model version. Every allocation includes an explicit confidence signal and human-readable drivers.

2. Design Goals, Constraints & Anti-Goals#

2.1 Success criteria#

• Train and evaluate on real, publicly retrievable logistics observations with checksums and chronological splits.
• Beat simple persistence and trend baselines on at least one predeclared holdout metric before claiming empirical value.
• Return non-negative allocations that sum to the requested budget within numerical tolerance.
• Respond predictably across risk and objective settings without hidden external services.
• Expose uncertainty and data maturity instead of presenting point estimates as certainty.
• Run in a portable open-source stack and serve the same inference contract through edge or container runtimes.

2.2 Hard constraints#

• No future-year features may enter an earlier training or calibration fold.
• No negative allocations, leverage, or unbounded concentration in the public demo.
• The inference route must remain compatible with both the Cloudflare Worker build and the Next.js standalone container build, without requiring the Python training stack at inference time.
• Public demo metrics must not be labeled as realized returns.
• Source datasets remain external unless redistribution terms explicitly permit bundling.

2.3 Anti-goals#

The system does not select securities, value individual companies, optimize taxes, guarantee returns, replace diligence, or infer company cash flows from aggregate freight activity. It is a transparent reference system for logistics allocation research and a deployment-ready shell for proprietary data.

2.4 Maturity#

The current release is a public-data research preview of AllocFormer-GTQ v0.1. It is suitable for architecture review, data-pipeline validation, interactive scenario exploration, and early partner conversations. Production use requires organization-specific targets, cash-flow outcomes, constraints, approval controls, monitoring, and prospective validation.

3. System Architecture#

3.1 Module map#

3.2 A thin decision seam#

The AllocFormer-GTQ v0.1 artifact is deliberately separated from the allocation policy. Forecast features, the relational-gate state, split-conformal radius, scenario-conditioned risk values, and covariance terms cross a small, versioned interface into the optimizer. This makes it possible to improve forecasting without silently changing portfolio constraints, or to change investment policy without retraining the predictor. The API reports both the model version and scenario identifier so decisions can be reproduced.

4. Data Model & Provenance#

4.1 Primary training source: FAF 5.7.1#

The Freight Analysis Framework is produced by the U.S. Bureau of Transportation Statistics with the Federal Highway Administration. FAF 5.7.1 includes regional freight estimates for 2018–2024 and exposes weight, value, and activity by origin, destination, commodity, mode, trade type, and distance band. The official site also publishes benchmark, forecast, state, and network-assignment variants.

The prototype uses the official FAF5.7.1_2018-2024.zip distribution. The downloaded archive used for this evaluation had SHA-256:

803036bb693a81fdf3e2c4a6d561feb71b102470c1602e9b35e3094e79485b71

Raw FAF rows are aggregated into decision-relevant series before fitting. Aggregation reduces sparsity, makes the public benchmark feasible on commodity hardware, and aligns the statistical unit with investable logistics sleeves rather than individual shipments.

FAF is an official federal statistical product, but the flow-download landing page does not display a file-specific open-data license. A related FAF5 network-node catalog record is explicitly CC0; that record must not be treated as automatically licensing every FAF distribution. The pilot records the exact flow URL and archive hash, and a commercial release must retain a terms snapshot and confirm the rights for the specific flow file.

4.2 Exogenous context: BTS indicators#

The BTS Supply Chain and Freight Indicators dataset combines timely port, rail, truck, labor, capacity, and cost measures. Its official inventory record labels the compilation Public Domain U.S. Government and exposes a 12-column source-aware schema. The evaluation snapshot was retrieved from Socrata dataset y5ut-ibwt; its downloaded CSV had SHA-256:

97692a23226b2333f395e20b188d995ab17fcc096f0c4d6974b293cf2b086221

Only indicators with stable definitions and adequate coverage enter the benchmark. Series-specific notes and source fields are retained because BTS describes the selected measures as provisional, multiple series experienced definition/source changes, and some inputs originate with third-party providers. The public-domain catalog label applies to the BTS compilation; it does not erase separate rights in an underlying third-party database or permit unsupported redistribution of that source.

4.3 Expansion datasets#

The production roadmap includes:

These are candidate or excluded expansion sources, not a declaration that they are all commercially compatible. None is represented in the reported v0.1 benchmark.

4.4 Leakage and quality controls#

• All splits are chronological.
• Missing and non-finite values are rejected or handled by declared transforms.
• Feature statistics are fit on training periods only.
• Dataset URLs, retrieval dates, row counts, and hashes are stored with artifacts.
• Each source is classified as observed, estimated, provisional, projected, synthetic, or scenario-assumed; these classes are not mixed silently.
• Dataset and code licenses are recorded separately, with a snapshot of the accepted terms for each downloaded distribution.
• Provisional indicators and definition changes are surfaced as limitations.
• The raw official archives are not committed to the application repository.

5. Forecasting Architecture#

5.1 Global single-target robust residual regression#

For each aggregated logistics series, AllocFormer-GTQ v0.1 derives level, log-growth, lagged growth, value-per-ton, miles-per-ton, and related temporal features from freight value, tonnage, and ton-miles. Exogenous BTS indicators encode system-wide activity and friction regimes. One global, regularized Huber-IRLS regression is fitted across panel rows and predicts the single y_growth target; it learns a correction over transparent persistence and damped-trend priors. “Shared” means one coefficient vector and one target across the panel, with no separate task-specific output heads. Robust weighting limits the leverage of extreme residuals; it does not make the model immune to structural breaks. The reported decision target remains aggregate freight opportunity, not an investment-return label.

5.2 Validation-gated relational context pooling#

Candidate series are related when they share an origin, mode, commodity, or network-wide regime. The optional block pools chronological context over those declared relations using only information available at the prediction cutoff. Architecture selection compares the block on and off using the validation period alone; the later holdout does not select the gate. The gate disabled relational pooling in the shipped v0.1 artifact, so the release does not attribute benchmark lift to relational context. The block is a graph-conditioned inductive bias, not a transformer or a full message-passing GNN.

5.3 Validation-selected ensemble and scenario-conditioned risk head#

The opportunity forecast blends the learned residual estimate, a damped trend, and persistence using weights selected only on the validation period. The fitted artifact stores robust normalization statistics, coefficients, blend weights, feature names, and the relational-gate state required for deterministic portable inference. Its source data stop in 2024. The versioned runtime input faf5.7.1-2025-one-step-v1 is a one-step 2025 model output carried forward as an extrapolated annual mode-growth prior for a research decision dated July 11, 2026. It is not observed 2025 data, a fresh 2026 forecast, or evidence of post-2024 validation.

A separate deterministic, scenario-conditioned risk head maps the opportunity forecast, scenario priors, historical cross-sleeve covariance, horizon, risk tolerance, and strategic-objective settings into downside and utility terms for allocation. It is a declared decision rule, not a second supervised model. Its return priors are transparent scenario assumptions; they are not labels learned from FAF and are not represented as backtested investment returns.

5.4 Split-conformal calibration#

Absolute log residuals from a held-out chronological calibration split define a split-conformal radius, which is stored independently from the production fit and applied symmetrically in log space. The holdout is used to measure interval behavior, not to refit that radius. Classical split-conformal coverage depends on exchangeability; annual freight series are temporally dependent and can shift. AllocAI therefore reports observed coverage and interval width as empirical diagnostics, not a distribution-free guarantee or a probability of investment success.

6. Risk-Aware Allocation#

6.1 Objective#

Given a budget $B$, the v0.1 optimizer chooses fully invested, long-only sleeve weights $w$ inside declared lower and upper boxes. It balances scenario-conditioned expected opportunity, resilience, decarbonization, covariance/concentration, and downside risk:

where $\mu$ is scenario-conditioned opportunity, $r$ is resilience contribution, $c$ is decarbonization contribution, $d$ combines execution, conformal-radius, mode-growth, and return-shortfall terms as a scenario-conditioned downside/CVaR proxy, and $\Sigma$ is the artifact's regularized cross-sleeve covariance derived from historical mode-growth exposures. User controls map to bounded coefficients. The covariance, diversification term, and explicit boxes prevent a superficially attractive single sleeve from consuming the portfolio. The implementation uses fixed-iteration projected-gradient ascent on the box-constrained simplex. In v0.1, “mean–CVaR” denotes a linear downside penalty plus a Gaussian-tail diagnostic, not an exact sample-average CVaR program with auxiliary tail variables. The reported cvar95 diagnostic is $2.0627$ times modeled portfolio volatility plus an execution-downside adjustment. It is an approximation, not a simulated loss distribution, convergence certificate, or realized-risk estimate. The objective is a modeled utility function, not an estimate of investor utility or realized alpha.

riskTolerance is a preference coefficient, not a requested downside-risk target. Moving it toward 1 relaxes covariance and linear downside penalties; it does not instruct the API to return a larger downsideRisk. Because every setting reoptimizes the portfolio, the Gaussian-tail diagnostic can move non-monotonically after reallocation. Sensitivity tests therefore require finite, distinct, feasible solutions across settings rather than an artificial direction-of-change assertion.

6.2 Constraints#

• $w_i \ge 0$
• $\sum_i w_i = 1$
• sleeve-specific lower and upper box constraints
• finite input ranges for budget, horizon, risk, and objectives
• deterministic projection back onto the feasible simplex

The API accepts capital in USD millions with at most two decimal places. It computes amounts from the final normalized weights in the same cent-of-a-million accounting unit, with the largest-weight sleeve absorbing the rounding residual so accepted capital is conserved exactly in integer accounting units. Inputs with finer precision, such as 1.005, are rejected rather than silently rounded.

6.3 Why optimization is separate from prediction#

A high-growth mode can still receive less capital when its modeled downside is severe, its covariance contribution is high, a box constraint binds, or the user prioritizes resilience or emissions. Keeping the mean–CVaR-proxy quadratic optimizer explicit makes that trade-off inspectable and testable.

7. Serving & Product Interface#

The inference service is implemented as a typed Next-compatible route that declares the edge runtime. It validates the request, loads the portable AllocFormer-GTQ v0.1 artifact, constructs scenario-conditioned utility and downside inputs, calls the deterministic box-constrained allocator, and returns allocations, portfolio diagnostics, confidence, and concise explanations. Vinext compiles the route to a Cloudflare-compatible Worker; the separate container build produces Next.js standalone output for a Node.js runtime. Both targets execute the same checked-in inference and optimizer code. No third-party model service or secret is needed for the public artifact.

The repository's three-stage Dockerfile pins Node 22 Alpine by digest, installs with npm ci, copies only the public assets and traced standalone server into the final image, disables telemetry, binds to 0.0.0.0, honors the injected PORT with a local default of 8080, and runs as the non-root node user. Its local health check calls GET /api/allocate, which loads and summarizes the embedded model artifact. Python, raw training data, databases, volumes, and external model APIs are absent from the runtime image. Linux/amd64 and arm64 builds were exercised locally; the resulting images were approximately 79–80 MB and served the page plus both allocation API methods. This proves packaging compatibility, not a deployed Cloud Run service, configured Cloud Run probe, production SLA, or production latency result.

The application implements no distributed rate limiter and deliberately persists no allocation request in application storage; a hosting provider can still retain ordinary infrastructure logs. A future Cloud Run operator must separately choose IAM/public access, ingress, quotas, WAF or gateway controls, log retention, and service-level health probes.

The response path applies baseline HTTP hardening: a content-security policy, strict-origin referrer policy, MIME sniffing protection, frame denial, a restricted permissions policy, and no-store API caching. The current CSP still permits inline scripts and styles for framework compatibility, so it is not represented as a strict nonce-based policy.

The product surface uses React with a custom WebGL logistics network. The network is not decorative video: node energy, links, and scene behavior react to allocation and risk settings. Semantic controls, values, explanations, and fallbacks remain available outside the canvas. Reduced-motion and graphics-failure paths preserve core use.

8. Determinism & Reproducibility#

Determinism matters because an allocation must be auditable after the fact. At a fixed version:

• source snapshots are addressed by hash;
• aggregations and splits are stable;
• training seeds and numerical tolerances are declared;
• inference contains no random branch;
• request normalization is explicit;
• allocations are projected to the same feasible simplex;
• model and scenario identifiers are returned with every response.

For this release, the authoritative model identity is AllocFormer-GTQ/0.1.0; the shorter AllocFormer-GTQ v0.1 name is used in prose. Runtime mode-growth inputs are separately identified as faf5.7.1-2025-one-step-v1. Every response discloses data through 2024, prior forecast year 2025, and decision date 2026-07-11. Determinism means repeatability under the same artifact, vintage, request normalization, and runtime assumptions, not correctness or freshness of the economic priors.

The training pipeline emits a machine-readable metrics file and a portable inference artifact. The application does not recompute benchmark metrics at runtime.

9. Interpretability & Confidence#

AllocAI exposes three kinds of explanation:

1. Input sensitivity: how risk tolerance, horizon, and strategic objectives changed the solution.
2. Sleeve drivers: the freight, network, macro, resilience, and carbon terms supporting each sleeve.
3. Confidence state: a bounded heuristic derived from observed holdout coverage, with penalties for horizon and capital-scale extrapolation.

The split-conformal radius is retained in the artifact and contributes to sleeve risk scores, but it is not itself returned as the API confidence field. Confidence is intentionally bounded and conservative. It is not a credit rating, posterior probability, causal attribution, calibrated probability, or guarantee. Model coefficients and any evaluated relational context are predictive evidence only. In a production deployment, these explanations should be supplemented with organization-specific feature attributions, constraint diagnostics, drift alerts, and an approval record.

10. API Surface#

10.1 Request#

POST /api/allocate
Content-Type: application/json

{
  "capital": 100,
  "riskTolerance": 0.55,
  "horizonYears": 5,
  "objectives": {
    "growth": 0.55,
    "resilience": 0.30,
    "decarbonization": 0.15
  }
}

capital is expressed in USD millions with at most two decimal places. Risk tolerance and objective weights are normalized fractions on $[0,1]$; the objective weights are normalized again by the server and must contain at least one positive value.

The endpoint requires Content-Type: application/json and caps request bodies at 16 KiB using both the declared Content-Length, when present, and the measured UTF-8 body. Unsupported media types return 415, oversized bodies return 413, malformed JSON returns 400, and valid JSON outside the model domain returns 422. Distributed rate limits belong at the hosting edge, where client identity and shared request state are available; v0.1 does not pretend that an isolate-local counter is a production rate limiter.

10.2 Response shape#

{
  "scenarioId": "...",
  "modelVersion": "...",
  "vintage": {
    "dataThrough": 2024,
    "priorForecastYear": 2025,
    "decisionAsOf": "2026-07-11",
    "scenarioLabel": "2026 research scenario: extrapolated annual mode-growth prior; not observed 2025 data or a current forecast"
  },
  "allocations": [
    {
      "id": "...",
      "label": "...",
      "amount": 0,
      "share": 0,
      "expectedReturn": 0,
      "riskScore": 0
    }
  ],
  "metrics": {
    "expectedIrr": 0,
    "downsideRisk": 0,
    "serviceLevelDelta": 0,
    "carbonDelta": 0,
    "confidence": 0
  },
  "explanation": []
}

Business-facing outcome fields in the public demo are scenario-model outputs, not realized or backtested financial returns.

The response key expectedIrr is retained for frontend compatibility, but the value is the allocation-weighted annual scenario return prior. It is not an internal rate of return solved from dated cash flows; v0.1 models no capital-call or exit schedule.

The required vintage object prevents the 2025 one-step prior from being presented as current in July 2026. The same metadata and the annual-prior version appear in the model-summary endpoint.

11. Performance Evaluation#

11.1 Methodology and environment#

The evaluation uses a chronological design. Training, validation, calibration, and holdout boundaries are fixed before scoring. Aggregate freight observations are transformed using training-only statistics. Results are compared with simple baselines that are difficult to beat honestly on short macroeconomic series: persistence and linear trend. Metrics are calculated on the same non-missing holdout rows with identical weighting.

11.2 Corpus#

The hash-verified FAF5.7.1 archive contains 2,494,901 raw rows. Streaming aggregation produces 25,385 domestic-origin-region × domestic-mode × SCTG2-commodity series with annual value, tons, and ton-miles for 2018–2024. Model/blend/context selection fits 50,770 examples from the 2021 and 2022 targets and evaluates 25,385 validation examples in 2023. The final reported model refits 76,155 examples through 2023 and is scored once on 25,385 untouched 2024 examples. The production artifact subsequently refits 101,540 examples through 2024 to form a one-step 2025 prior. For the July 2026 research decision it uses the resulting growth rate only as an extrapolated annual prior; no observed 2025 data enter the artifact, and the forward refit does not alter the reported holdout result.

The pinned BTS Supply Chain Indicators snapshot contains 25,892 source observations plus its header. Six selected activity/friction series are annualized into lag-safe covariates; eight annual macro records are retained in the derived adapter output. Raw source counts, derived counts, URLs, and SHA-256 digests are separated in data/provenance.json.

11.3 Forecast quality#

The selected pilot improves WAPE by 0.0747 percentage points, or 1.47% relative, and MASE by the same relative amount versus persistence. It does not dominate every metric: persistence is materially better on unweighted sMAPE, by 10.34 percentage points. The very high proportion of zero and near-zero cross-sectional flows makes that metric especially sensitive, but it remains reported rather than discarded. Selection-year 2023 WAPE was 5.2996%.

The evidence supports only the narrow statement that the custom model modestly improves scale-weighted error over the declared public-data baselines on this split.

11.4 Calibration and allocation checks#

The nominal 80% split-conformal interval uses a validation log-radius of 0.21216 and covers 82.10% of the 2024 holdout. Its median relative interval width is 46.80%. Coverage is therefore close to nominal, but the wide intervals and single calibration year are evidence of uncertainty, not a guarantee.

The validation-only architecture gate compared relation-pooled context off versus on without consulting 2024. On 2023, off achieved 5.2996% WAPE versus 5.3429% for on, so the shipped artifact disables relational context. The untouched 2024 comparison is directionally consistent: 5.0216% WAPE off versus 5.0660% on. Removing BTS macro features increases holdout WAPE from 5.0216% to 5.0431%; this small ablation difference is descriptive, not a causal macro-feature claim.

As rerun on July 23, 2026, the checked-in JavaScript suite passes 8/8 tests after a production Worker build: server rendering, deterministic API replay, invalid-domain and malformed-JSON rejection, media-type/body-size enforcement, artifact/architecture-gate integrity, exact share and budget reconciliation, capital-precision validation, and risk/objective-extreme feasibility without imposing a monotonic risk target. Two independent Python unit tests also pass in the configured training runtime, covering deterministic fitting/prediction and metric identities. npm run lint and strict TypeScript checking pass as separate gates.

A supplemental 80-case stress grid spans risk tolerances 0, 0.25, 0.50, 0.75, and 1.00; horizons 1, 5, 10, and 30 years; and growth-only, resilience-only, decarbonization-only, and balanced objectives. All 80/80 requests were feasible and exactly budget conserving, producing 78 distinct portfolios. The maximum observed share-sum error before response reconciliation was $2.22 \times 10^{-16}$, and the maximum accounting error was zero cent-of-a-million units. These counts are supporting engineering evidence from a read-only local run, not a checked-in forecast benchmark or a business-outcome backtest.

The release gate requires empirical interval diagnostics, budget conservation, non-negativity, bound compliance, multi-scenario preference sensitivity and feasibility, and deterministic replay.

11.5 Objective-isolation decision sensitivity#

To test whether each strategic control changes the portfolio in its intended direction, a deterministic sensitivity benchmark compared the optimized result with a feasible equal allocation of 16.6667% in each of six sleeves. The headline case uses an accepted USD 100 million mandate, a five-year horizon, risk tolerance 0.50, and one normalized strategic objective at a time. Capital sets the reported amounts but does not change v0.1 portfolio shares; horizon, risk tolerance, objectives, priors, covariance, and sleeve bounds drive the weights.

The production API's reconciled six-decimal shares were used for the candidate portfolio. For any target metric, relative lift is $100(\mathrm{optimized}-\mathrm{equal})/\mathrm{equal}$. A 45-case sweep (three isolated objectives × risk tolerances 0, 0.25, 0.50, 0.75, and 1.00 × horizons 2, 5, and 10 years) returned HTTP 200, satisfied every sleeve bound, conserved the budget, and produced positive targeted lift in all 45/45 cases. Relative-lift ranges were 5.77–6.47% for the annual return prior, 11.03–11.91% for service-level lift, and 43.93–44.80% for carbon reduction.

A separate 80-case calculation compared the optimizer's exact internal objective with equal weighting. Median modeled-utility lift was 8.29%; all 80 cases were positive and the minimum was 2.05%. This is a solver-consistency result: the optimizer is designed to maximize that same declared objective, so the comparison is partly circular and is not independent evidence of investment performance.

The three table rows are three separately reoptimized mandates, not simultaneous gains from one portfolio. Both the optimizer and equal-weight reference are scored using the same stored, hand-authored return, service, carbon, and execution-risk assumptions. Equal weighting is feasible but is not an optimized, historical-share, or investable-market benchmark. There is no oracle comparison, paired confidence interval, realized-outcome label, or independent decision backtest. The resilience-only result also raises the modeled downside diagnostic from 6.5513% to 7.0635%; prioritizing one objective entails trade-offs. Accordingly, the table demonstrates modeled policy responsiveness, not realized return, observed SLA improvement, measured emissions abatement, causality, or alpha.

11.6 Latency#

On the checked-in July 11 local warm-path benchmark (Node.js v23.11.0 on arm64, built Worker imported in-process, 50 warmups followed by 400 sequential requests with response bodies consumed), the mean inference time was 2.1718 ms, p50 2.1403 ms, p95 2.4092 ms, and p99 2.6578 ms. The exact harness is scripts/benchmark-api.mjs, invoked by npm run benchmark:api; the captured result is ml/artifacts/latency-v0.1.0.json. Two supplemental July 23 reruns of the same local harness produced mean latency between 2.4486 and 2.4566 ms and p99 between 4.0095 and 4.7780 ms; they are dated reproducibility checks and do not replace the pinned artifact.

None of these measurements is a production or Cloud Run latency claim. They exclude network transit, cold starts, concurrency and load, container startup, autoscaling, deployed Cloudflare or Cloud Run isolation and scheduling, browser work, and build time. No deployed Cloud Run latency artifact exists for this release.

12. Correctness & Quality Assurance#

The verification suite covers:

• request validation and bounded inputs;
• deterministic replay;
• allocation sum, precision, non-negativity, and sleeve-bound invariants;
• graceful handling of malformed JSON;
• model artifact hash, schema, covariance symmetry, and feasible bounds;
• reported baseline ordering and the validation-selected architecture gate;
• deterministic Python fitting and metric identities;
• server-rendered product identity and published-paper parity; and
• production Worker build compatibility.

Container verification is a separate gate because the checked-in JavaScript suite exercises the Worker build. Local release checks built both Linux/amd64 and arm64 standalone images, started the container as UID 1000, observed a healthy local status, and received HTTP 200 from /, GET /api/allocate, and a valid POST /api/allocate. The final image contained neither the raw ml/ or data/ trees nor a Python runtime. Docker's static build check reported no Dockerfile warnings. These checks establish packaging and smoke-test compatibility only; they do not establish Cloud Run availability, load capacity, autoscaling behavior, or a service-level objective.

A point-in-time npm advisory check on July 23, 2026 reported seven high-severity and zero critical findings across the full dependency graph, including two high-severity findings in the production dependency graph through the Next.js/Sharp chain. This supersedes the clean July 11 snapshot and remains an open remediation item before public production promotion. An advisory count is not an exploitability assessment, but it must not be represented as a clean dependency audit. The release also lacks a checked-in SBOM, image-signing policy, automated image scan, and base-image refresh workflow.

Accessibility, reduced-motion, WebGL fallback, and context-loss behavior received source-level review but are not represented as automated browser tests in this release. Tests prove only their stated invariants. They do not establish profitability, causal impact, or suitability for a particular investor.

13. Licensing & Data-Governance Posture#

The runtime application uses an open web stack. Dataset provenance is recorded independently from code, dependency, and model-artifact licensing because those rights are distinct.

• The BTS Supply Chain and Freight Indicators inventory labels its compilation Public Domain U.S. Government. Source and note fields are retained because some series use third-party inputs or change definition.
• FAF flow files are retrieved from the official BTS page and pinned by hash. A related FAF network-node catalog entry is CC0, but the v0.1 flow-download page does not display a file-specific license; commercial redistribution or downstream licensing therefore requires a distribution-specific terms record rather than an inference from the network entry.
• The World Bank LPI catalog record is public under CC BY 4.0 and requires attribution and change notices.
• OpenStreetMap data are ODbL 1.0, with attribution and database share-alike obligations. Any OSM-derived feature store must remain separable and pass an approved compliance review before production use.
• UN Comtrade is not an open commercial-training source under its current license agreement. It is excluded absent prior written permission from the United Nations.
• SupplyGraph's repository reports LGPL-2.1 for code. That repository license is not assumed to settle rights in company-contributed benchmark data; the candidate remains research-only pending a dataset-specific review.

The application stores the derived AllocFormer-GTQ v0.1 artifact and small fixtures rather than redistributing the large raw archives. No dataset is assumed to inherit a downloader's code license, and no model artifact is assumed to inherit a dataset license automatically.

Before production training, an operator should complete a data protection impact assessment, document retention and deletion rules, verify each distribution/vendor/API term, generate a dependency and data-rights manifest, and establish model-risk ownership. No private shipment, employee, customer, or geolocation record is used in the public benchmark.

14. Comparison to Prior Art#

AllocAI draws conventions from, but does not copy, several research directions:

• Temporal Fusion Transformers combine variable selection, gating, and temporal attention for interpretable multi-horizon forecasting.
• PatchTST demonstrates strong long-horizon results from patched, channel-independent time-series representations.
• SupplyGraph establishes a public graph benchmark for supply-chain planning tasks.
• Learning production functions for supply chains with GNNs combines temporal graph learning with an inventory module and an open simulator.
• Probabilistic demand forecasting with GNNs joins graph encoders with probabilistic forecasting.
• Differentiable convex optimization layers formalize end-to-end learning through constrained optimization problems.
• Adaptive conformal prediction for time series and sequential predictive conformal inference address uncertainty under temporal dependence.

AllocFormer-GTQ v0.1 does not reimplement those systems. Its current forecast core is robust residual regression with a validation-selected learned/trend/persistence ensemble; its optional relation-pooled feature block was disabled by the validation-only architecture gate. The model-family name does not imply that the shipped artifact is a transformer or full GNN. Likewise, differentiable convex layers are a research antecedent and possible future direction, not part of v0.1: the current allocator is a separately fitted, deterministic projected-gradient solver for a box/simplex-constrained quadratic objective with a linear downside proxy.

AllocAI's v0.1 contribution is the compact integration of official freight data, robust residual forecasting, validation-only architecture selection, chronological split-conformal diagnostics, a scenario-conditioned risk head, explicit constrained allocation, portable deterministic inference, and an interactive decision surface. The underlying mathematical ideas have well-established antecedents.

15. Limitations & Future Work#

1. Short annual history. FAF's current annual panel contains many cross-sectional rows but few time steps. Cross-sectional pooling cannot create missing economic regimes.
2. Aggregate target mismatch. Freight activity is not a company cash flow, asset return, or causal treatment effect.
3. Revisions and forecasts. Public macro series may be revised, and some source indicators are provisional.
4. Geographic scope. The reported core benchmark is U.S.-centric.
5. Model class. v0.1 is robust residual regression with an ensemble, not a transformer, full message-passing GNN, or learned joint scenario generator. The family name describes a roadmap as well as the pilot.
6. Relational evidence. The relation-pooled feature block did not earn activation under the validation-only gate. It is available for research, but the shipped artifact disables it and makes no claim that relational pooling improves this benchmark.
7. Calibration sample and dependence. One chronological calibration period is a limited basis for interval assessment. Temporal dependence and distribution shift weaken classical split-conformal assumptions, so observed coverage is descriptive rather than guaranteed.
8. Financial assumptions. Return priors are transparent scenario assumptions, not targets learned from FAF or backtested investment returns. The allocator chooses among six preset sleeves rather than securities or arbitrary projects.
9. Optimization approximation. The downside term and cvar95 output use a deterministic proxy and Gaussian-tail approximation. v0.1 is not an exact scenario CVaR program, a differentiable optimizer, or a cash-flow simulator.
10. No transaction model. The public demo omits tax, liquidity, financing, construction timing, execution costs, and staged capital calls.
11. No causal claim. Allocation outputs rank modeled opportunity under assumptions; they do not prove that spending causes the projected outcome.
12. Elapsed temporal prior. The runtime uses a 2025 one-step model output derived from data through 2024 as an extrapolated annual prior for a July 2026 research scenario. It is not a current forecast; production promotion requires refreshed data, a new vintage, and post-2024 out-of-time evaluation.
13. Objective-isolation scope. The supplemental decision study tests three separately reoptimized modeled mandates against feasible equal weighting. It does not show simultaneous gains, use observed outcomes, establish causality, or compare against a stronger optimized or investable benchmark.
14. Deployment and security evidence. The image is Cloud Run-ready, but no Cloud Run service, production probe, load test, cold-start distribution, autoscaling result, or end-to-end latency result is reported. Current dependency advisories remain open, and the release still needs an SBOM, image signing, automated scanning, and a base-image refresh policy before production promotion.

The production roadmap is to add proprietary lane economics and project cash flows, rolling and horizon-specific calibration, multi-frequency encoders, governed scenario generation, solver optimality diagnostics, transaction and capital-call constraints, drift monitoring, and prospective shadow-mode evaluation. Hierarchical graph attention, relational conformal methods, and differentiable constraint learning remain research candidates that must pass ablation and decision-regret gates before controlled capital deployment.

16. Conclusion#

AllocAI demonstrates a practical architecture for moving from logistics data to constrained capital decisions without hiding uncertainty, scenario assumptions, or feasibility rules. The public release supplies AllocFormer-GTQ v0.1, a real-data pipeline, a typed portable API with Cloudflare Worker and Cloud Run-ready standalone-container targets, a responsive WebGL product experience, and reproducible benchmark artifacts. Its empirical claims are limited to the disclosed chronological evaluation, and its supplemental decision-sensitivity gains remain modeled comparisons rather than observed outcomes. Its current value is as a foundation for institution-specific targets, constraints, and prospective validation, not as a substitute for investment judgment.

17. Appendices#

Appendix A: Reproduction#

# Download the two exact official snapshots.
curl -L https://faf.ornl.gov/faf5/data/download_files/FAF5.7.1_2018-2024.zip \
  -o /tmp/FAF5.7.1_2018-2024.zip
curl -L 'https://data.bts.gov/resource/y5ut-ibwt.csv?$limit=50000' \
  -o /tmp/bts_supply_chain.csv

# Create the pinned training environment and reproduce model, metrics,
# derived aggregate, and provenance files.
python3 -m venv .venv
.venv/bin/pip install -r ml/requirements.txt
.venv/bin/python ml/train.py \
  --faf /tmp/FAF5.7.1_2018-2024.zip \
  --bts /tmp/bts_supply_chain.csv

# Verify the edge application, model artifact, API invariants, Python model,
# lint, and captured local latency protocol.
npm test
PYTHONPATH=ml .venv/bin/python -m unittest discover -s ml/tests -v
npm run lint
npm run typecheck
npm run benchmark:api

# Verify the standalone Cloud Run container build path. The running process
# honors Cloud Run's injected PORT; 8080 is the local default.
docker build --platform linux/amd64 -t allocai:cloudrun .
docker run --rm -p 8080:8080 -e PORT=8080 allocai:cloudrun

# Verify the portable model digest recorded in the manifest.
shasum -a 256 ml/artifacts/allocformer-gtq-v0.1.0.json

The raw files must match FAF SHA-256 803036bb693a81fdf3e2c4a6d561feb71b102470c1602e9b35e3094e79485b71 and BTS SHA-256 97692a23226b2333f395e20b188d995ab17fcc096f0c4d6974b293cf2b086221; the adapter rejects mismatches. The portable model artifact is 13,367 bytes with SHA-256 84183b3e4ef062024e66db88c9ec2a90ee33385d0ed5fc38fc9f25e8a9b4193c, recorded in ml/artifacts/MANIFEST.json. Raw official data are intentionally not committed; only the compact derived aggregate, metrics, manifest, and edge artifact are stored.

Appendix B: Confidence labels#

Appendix C: Reproducibility checklist#

• Exact training command recorded
• Primary source URL recorded
• Source hashes recorded
• Chronological split counts recorded
• Model artifact hash recorded
• Baseline and custom metrics recorded
• Supplemental decision sensitivity explicitly labeled modeled
• Determinism test green
• API invariant tests green
• Cloudflare-compatible Worker production build green
• Next.js standalone Linux container build and smoke test green
• End-to-end Cloud Run deployment and production latency measured
• Production dependency advisories remediated; SBOM, image signing, and automated image scanning in place

Appendix D: Glossary#

• CVaR: Conditional Value at Risk; expected loss in a specified worst tail. AllocAI v0.1 reports a Gaussian-tail approximation and uses a linear downside proxy rather than solving exact scenario CVaR.
• FAF: Freight Analysis Framework.
• GNN: Graph Neural Network.
• OD: Origin–destination.
• Sleeve: A bounded category within the capital portfolio.
• Split conformal: Calibration of a prediction set from residuals held apart from model fitting; its classical finite-sample guarantee depends on assumptions that temporal freight data may violate.
• sMAPE: Symmetric mean absolute percentage error.
• Temporal holdout: Evaluation on a later period that was unavailable during fitting.

References#

All URLs accessed July 2026.

1. U.S. Bureau of Transportation Statistics and Federal Highway Administration. Freight Analysis Framework 5.
2. U.S. Bureau of Transportation Statistics. Supply Chain and Freight Indicators data inventory.
3. World Bank. Logistics Performance Index.
4. OpenStreetMap Foundation. Copyright and License.
5. United Nations Statistics Division. UN Comtrade licence agreement.
6. Wasi, A. T., Islam, M. S., and Akib, A. R. SupplyGraph: A Benchmark Dataset for Supply Chain Planning using Graph Neural Networks, 2024.
7. Chang, S. et al. Learning production functions for supply chains with graph neural networks, 2024.
8. Kozodoi, N. et al. Probabilistic Demand Forecasting with Graph Neural Networks, 2024.
9. Lim, B. et al. Temporal Fusion Transformers for Interpretable Multi-horizon Time Series Forecasting, 2021.
10. Nie, Y. et al. A Time Series is Worth 64 Words: Long-term Forecasting with Transformers, 2023.
11. Agrawal, A. et al. Differentiable Convex Optimization Layers, 2019.
12. Zaffran, M. et al. Adaptive Conformal Predictions for Time Series, 2022.
13. Xu, C. and Xie, Y. Sequential Predictive Conformal Inference for Time Series, 2023.
14. Google Cloud. Cloud Run container runtime contract.
15. Google Cloud. Continuously deploy from a repository.

Release context. Primary model evaluation: July 11, 2026. Supplemental decision and deployment verification: July 23, 2026. Primary implementation: ml/, lib/, app/api/allocate/, and Dockerfile. Deployment targets: private Cloudflare-compatible preview and a standalone Node.js container for Google Cloud Run.

Decision-use notice. AllocAI is an experimental decision-support system, not investment advice. AllocFormer-GTQ v0.1 is a near-SOTA-inspired pilot, not a state-of-the-art claim. Its public-data benchmark measures a research prototype on aggregate freight signals; it is not evidence of future investment returns, a production SLA, or performance outside the disclosed split. Supplemental growth, resilience, and decarbonization uplifts are deterministic within-model scenario comparisons against equal weighting, not observed business outcomes.