1. System Objective

ATLAS is a measurement and decision-governance system for portfolio exposure under uncertainty. It does not maximize a point-estimate return. Its objective is to manage exposure when structural macro conditions and tactical classification certainty are unstable.

A decision at time \(t\) is a function of structural state, tactical instability, confidence, disagreement, portfolio constraints, and governance state:

where \(S_t\) is structural regime, \(T_t\) is tactical instability, \(C_t\) is confidence, \(D_t\) is disagreement, \(\mathcal{K}_t\) is the set of portfolio and sleeve constraints, and \(G_t\) is governance state.

The admissible decision space is

In the current implementation the live posture set is \(\{\mathrm{Allocate},\; \mathrm{Reduce},\; \mathrm{Abstain}\}\). Hold is the absence of a target change; hedge is implemented through the optionality-protection workflow. Abstention is a first-class governed result, not an error condition.

2. Structural Regime and Tactical Instability

2.1 Structural regime

The structural regime is a slow, persistent classification of the macro-financial environment. In the live implementation the score axes are growth, inflation, risk appetite, and liquidity. Conceptually:

\(\Theta_S\) denotes governed structural parameters, including the transition matrix \(P\) with \(P_{ij} = \mathbb{P}(S_{t+1}=j \mid S_t=i)\). The regime is estimated on a declared calibration window and is held out from out-of-sample evaluation. Persistence is enforced by construction: the structural layer is not redefined by short-run tactical motion.

2.2 Tactical instability

Tactical instability is a fast, reversible overlay on the structural regime. It measures whether classification certainty is stable, deteriorating, or unobservable. The live implementation classifies each day as Stable, Transitional, or Unstable from:

where \(F_t\) is flip risk, \(\Delta^2 F_t\) is flip-risk acceleration, \(C_t\) is confidence, \(\Delta C_t\) is confidence change, \(D_t^{\,\text{score}}\) is score disagreement, and \(N_t\) is an NA-driven indicator. NA-driven or inadmissible inputs fail closed: they cannot resolve to Stable.

3. Regime Topology and State Evolution

ATLAS measures not only the current regime level but also movement through score space. Where supported by diagnostic artifacts, the score vector \(\tilde{Z}_t\) in a three-dimensional embedding is tracked over time:

Finite-difference kinematics are computed on this embedding:

The following geometric quantities are produced by diagnostic producers. They are descriptive, not decision-authoritative, unless explicitly noted:

Quantity	Producer	Status	Decision authority
position \(\tilde{Z}_t\)	score pipeline	LIVE	live input to regime and confidence
velocity \(\|\Delta \tilde{Z}_t\|\)	regime_geometry_diagnostics_daily	DIAGNOSTIC	none
acceleration \(\|\Delta^2 \tilde{Z}_t\|\)	regime_geometry_diagnostics_daily	DIAGNOSTIC	none
curvature proxy	regime_geometry_diagnostics_daily	DIAGNOSTIC	none
directional stability	regime_geometry_map_daily	DIAGNOSTIC	none
distance to boundary	regime_geometry_map_daily	DIAGNOSTIC	none (geometric confidence is shadow)
distance to centroid	regime_geometry_map_daily	DIAGNOSTIC	none
tortuosity ratio	regime_geometry_map_daily	DIAGNOSTIC	none
persistence band	regime_geometry_map_daily	DIAGNOSTIC	none
transition entropy	regime_geometry_map_daily	DIAGNOSTIC	none

The live confidence and flip-risk objects use the margin form on the structural-score axes (Section 4 and 5), not the geometric distance form above. Geometry is an interpretability layer; it does not gate allocations.

4. Confidence and Transition Risk

Confidence is proximity to a decision boundary, adjusted for measurement uncertainty, persistence, disagreement, and data validity. The live implementation uses a score-margin form:

where \(M_s(Z_t)\) is the margin assigned to structural state \(s\). A geometric distance to the decision boundary \(\Gamma\),

is computed as a SHADOW research diagnostic and is not wired into the admissibility map. In both formulations \(C_t \downarrow 0\) as \(Z_t \to \Gamma\).

Confidence is decomposed conceptually as

where \(d_t\) is boundary distance, \(U_t\) is measurement uncertainty, \(P_t\) is state persistence, \(D_t\) is model or score disagreement, and \(Q_t\) is data quality/freshness. The live code does not collapse these into one scalar; each contributes separately to abstention admissibility.

5. Flip Risk and Transition Pressure

Flip risk is a decomposed transition-risk measure. It is high when the score vector is near a regime boundary and moving quickly. The live series is computed as

with the properties that \(F_t\) is non-increasing in confidence and non-decreasing in score velocity. Flip-risk acceleration \(\Delta^2 F_t\) is one of the three live abstention triggers.

Flip risk is therefore not a directional forecast. It is a pressure indicator: the combination of boundary proximity and motion raises the chance that the structural assessment may need to change. Static threshold crossings alone are insufficient; change and acceleration matter more than level.

6. Disagreement

Score disagreement is the range across the structural-score axes used in the live admissibility map:

A large spread means the macro signals are sending inconsistent messages, which reduces confidence in any single structural label. \(D_t^{\,\text{score}}\) is a live input to abstention.

Surface disagreement, the indicator that two classification surfaces assign different structural labels, is measured but not wired into the live admissibility map. It remains a research track (WS7).

7. Abstention Mathematics

7.1 Abstention triggers

The live abstention engine evaluates three primary triggers:

• Confidence shock. A large absolute or percentage drop in \(C_t\) below configured thresholds.
• Flip-risk acceleration. A large second difference \(\Delta^2 F_t\) indicating rising transition pressure.
• Score disagreement. \(D_t^{\,\text{score}}\) exceeding a configured spread threshold.

Additional abstention drivers include stale or incomplete data (\(N_t=1\) or \(G_t=\mathrm{INADMISSIBLE}\)), an unresolved structural transition, and governance restrictions such as operator-imposed holds or unauthorized sleeves.

7.2 Meta-regimes

Two meta-regimes are distinguished conceptually:

Meta-regime	Meaning	Live mapping
TRANSITIONAL	Motion is coherent, but a stable destination is not yet established.	T_t = Transitional with measured triggers and severity_observability = COMPUTED
INDETERMINATE	Evidence is inconsistent, incomplete, unstable, or insufficiently resolved.	T_t = Transitional driven by NA_FAIL_CLOSED, INSUFFICIENT_HORIZON, or EVIDENCE_UNAVAILABLE

The implementation records the evidence basis explicitly so that an indeterminate state cannot masquerade as a measured transitional state.

7.3 Abstention response

When abstention is admissible, the system may respond with one or more of:

• capital preservation (no new exposure);
• gross reduction of existing risk (e.g., the graded Reduce posture);
• optionality retention or hedge ladder review;
• delayed commitment until persistence conditions are met;
• constrained allocation within tightened bounds;
• operator review and explicit override.

7.4 Outcome assessment

After an abstention episode ends, the outcome is classified at a pre-registered horizon:

• Justified Caution (JC): forward drawdown exceeded tolerance, so abstaining avoided realized loss.
• False Caution (FC): forward drawdown remained within tolerance, so abstaining was unnecessary.
• Inconclusive (IN): insufficient forward data or intermediate outcome.

These labels feed the LANTERN shadow confusion matrix and the abstention economics diagnostics. They are measurement, not policy.

8. Allocation and SHELOB

SHELOB is the governed allocation and portfolio-construction layer. The name is an internal identifier; its role is to produce and explain allocation outputs under regime state, uncertainty, constraints, and governance. It is not an autonomous allocator.

8.1 Optimizer families

Family	Status	Role
TILT	LIVE_AND_GOVERNED	Current policy baseline produced by portfolio_targets and consumed by operator surfaces.
MVO	SHADOW_OR_RESEARCH	Mean-variance diagnostic; security weights are bucket-proxy approximations.
Black-Litterman	SHADOW_OR_RESEARCH	Diagnostic counterfactual; not a live instruction.
EQW	SHADOW_OR_RESEARCH	Equal-weight reference; availability is honest-empty when the comparator artifact is missing.

8.2 Governed optimization problem

The portfolio-target stage solves a constrained allocation problem. A generic formulation that matches the implementation is:

subject to

where \(\Sigma\) and \(\mu\) are inputs, \(\mathcal{P}(w)\) captures penalty terms, and the linear constraints \(Aw \le b\) encode sleeve limits, concentration bounds, liquidity-tier scalers, and optionality gates. The default single-position cap is 20%. Cash absorption is used to renormalize after liquidity scaling.

8.3 From optimizer output to operative allocation

The operative allocation is not merely the mathematical optimizer output. It passes through:

• regime interpretation and tactical-instability gating;
• uncertainty controls (confidence, flip risk, disagreement);
• governance constraints and reason codes;
• data-validity checks and freshness labels;
• model-change controls and promotion state;
• operator-authorized overlays, if any.

The ANDURIL allocation overlay attaches to the decision-state response as an explanatory permission and reason stack. It emits no weights, targets, or trade instructions. NORMAL permission is only reached when every lane is positively confirmed clear; missing or unstable data fails closed to NO_ALLOCATION_ADVICE.

8.4 Infeasibility and audit trace

If constraints are mutually inconsistent, the target generator reports infeasibility through reason codes rather than emitting an ungoverned allocation. Every SHELOB surface is descriptive-only: it explains weights, availability, and readiness. Audit trace includes model family, artifact version, constraint set, and the governance state at the time of generation.

9. Pipeline and Artifact-First Architecture

ATLAS is built as an artifact-first pipeline. Derived analytics are pre-computed, schema-validated, and written as versioned artifacts before any UI or API consumer reads them. The logical sequence is:

Key consequences of this architecture:

• Downstream consumers read governed artifacts; they do not recompute analytics.
• Schema validation occurs at ingest and at artifact boundaries.
• Keys must be unique; dates use consistent classes; missing columns fail fast.
• Latest-available data is distinguished from incomplete current-day data.
• Stale data remains visibly stale.
• Production and research artifacts are stored in separate paths (derived_governance vs. derived_shadow).
• Pipeline manifests identify exactly what ran.

Each pipeline run produces a run manifest (schema version 2) with, where available:

The run manifest is observational and non-blocking: a manifest failure does not abort the pipeline, but it is recorded honestly. Artifact content hashes (SHA256) are written to pipeline_artifact_hashes_daily.parquet for later provenance queries.

10. Model-Change Auditing

Model changes are treated as governed events rather than ordinary code edits. A candidate model is evaluated against a baseline:

Across dimensions that include:

• output differences and regime-state changes;
• confidence changes and flip-risk changes;
• allocation changes and abstention changes;
• constraint breaches and missing-data behavior;
• historical replay and null/placebo tests;
• staleness behavior and computational reproducibility.

10.1 Change classification

Changes are classified by scope. The repository uses a version scheme of {generation}.{revision}.{calibration} and a changelog in config/model_changelog.yml. Conceptually:

Class	Meaning
NO_SEMANTIC_CHANGE	No effect on analytical outputs.
DISPLAY_ONLY	UI rendering change; no artifact change.
SCHEMA_CHANGE	Column, type, or contract change.
FEATURE_CHANGE	New or removed derived feature.
PARAMETER_CHANGE	Threshold, window, or scalar change.
MODEL_CHANGE	Estimator, regime map, or inference change.
DECISION_POLICY_CHANGE	Admissibility map or posture mapping change.
GOVERNANCE_CHANGE	Auth, promotion, or override rule change.

10.2 Change attribution

The system attempts to attribute an observed output change to one of: changed source data, data revision, schema change, code change, model version, parameter change, calibration-window change, operator override, or environment change. The R/helpers_ai_state_model_change.R reader produces daily-lag deltas with direction labels and closed-vocab status (AVAILABLE, MISSING, SCHEMA_INVALID, NOT_EVALUABLE, STALE, DEGRADED, UNKNOWN).

10.3 Promotion states and stop conditions

The promotion committee evaluates candidate changes against required gates. Verdicts include PROMOTE, REJECT, and HOLD. Candidate statuses include SHADOW, CANDIDATE, EVIDENCE_ACCUMULATING, PROMOTION_READY, PROMOTED, ACTIVE, and BLOCKED. A negative, inconclusive, or unstable result is a legitimate endpoint: a model is not promoted merely because it is newer.

11. Governance Mathematics

Governance determines whether an analytical result is informational, research-only, shadow, restricted, actionable, operator-required, or blocked. Action authority is a function of:

where \(E_t\) is entitlement state, \(V_t\) is data and model validity, \(F_t\) is freshness, \(R_t\) is research or production status, and \(O_t\) is operator authorization. The resulting authority level is drawn from a closed set:

Analytical strength does not automatically create operational authority. A validated model with stale inputs may be restricted; a shadow model with current inputs has no decision authority.

Governance enforcement includes:

• reason codes for every restriction or override;
• expiry timestamps on overrides;
• actor identity and tenant context;
• approval boundaries and break-glass write gates;
• append-only audit logs;
• production versus beta separation;
• fail-closed behavior and no silent fallbacks.

The governance override write seam is live in non-production environments; production contexts are forbidden by construction.

12. Auditability and Provenance

ATLAS is designed so that any decision can be reconstructed. A reviewer should be able to answer:

• What data were available?
• Which versions were used?
• Which pipeline ran?
• Which artifacts were produced?
• Which model produced the result?
• Which constraints applied?
• Was the result stale?
• Was the result research-only or actionable?
• Was there an override? Who authorized it?
• What changed from the prior run?

Provenance mechanisms include:

• append-only run manifests and artifact registries;
• per-artifact SHA256 content hashes;
• model identifiers and experiment identifiers;
• source hashes and actor IDs;
• reason codes and environment tags;
• tenant scope and run-id provenance classification;
• run provenance linkage with reproducibility verdicts (REPRODUCIBLE, PARTIALLY_REPRODUCIBLE, NOT_REPRODUCIBLE, INDETERMINATE).

The provenance API surfaces the artifact hash table. Historical reproducibility is explicitly marked as partial or indeterminate when source commit, image digest, or stage-definition anchors are missing.

13. Machine-Readable AI Briefing Architecture

AI prose in ATLAS is downstream of governed facts. The architecture is:

Key components:

• Briefing catalog. R/helpers_ai_state_registry.R registers briefing types such as CURRENT_SYSTEM_STATE, PORTFOLIO_OVERLAY_STATE, OPTIONALITY_STATE, with prompt versions, required payload fields, permission scope, and live-call policy.
• Context contract. R/helpers_ai_state_payload.R builds a governed JSON payload from artifacts including freshness, decision_outcomes_ledger_daily, abstention_now, and regime_overlay_state_daily.
• Parser/adapter. R/helpers_ai_state_adapter_contract.R and R/helpers_ai_state_briefing_context.R provide a machine-readable adapter and context builder with closed vocabularies and schema versions.
• Policy guardrails. Forbidden intents are scanned; trade-generation and target-mutation language are blocked; the output is marked descriptive_only = TRUE and allocation_authorized = FALSE.
• Live-call gate. The operational LLM route is gated by an environment flag and an API key. In the current deployment it fails closed with OPENAI_KEY_UNAVAILABLE.

The governed /v1/ai-briefing route reads a persisted artifact that is not currently materialized, so it returns AI_BRIEFING_SOURCE_MISSING. The legacy Shiny AI Briefing tab remains functional but is explicitly not integrated into the ARAGORN API. The machine-readable catalog and parser capability is implemented and tested; full end-to-end wire integration is still in progress.

14. Data Freshness and Validity

Scientific status and data validity are orthogonal. A validated method may be unusable when its inputs are stale. The following matrix is a public abstraction of the internal freshness and artifact-status logic:

Scientific status	Data status	Operational interpretation
Validated	Current	May be actionable if authorized
Validated	Stale	Restricted or informational
Validated	Missing	Unobservable / blocked
Inconclusive	Current	Research-only
Shadow	Current	No decision authority

Artifact statuses include OK, STALE, DEGRADED, MISSING, and CONTENT_STALE. Downstream artifacts inherit upstream non-OK states rather than masking them. Yesterday's regime state does not appear as current without an explicit freshness annotation.

15. Limitations

The following limitations are stated explicitly to prevent inferential drift:

• Regime classification is uncertain; historical relationships may change.
• Model outputs depend on data quality, revisions, and the completeness of cross-asset inputs.
• Regime topology describes geometry, not causality.
• Confidence is not certainty; a high-confidence day can still precede a regime change.
• An optimizer does not eliminate model risk or tail risk.
• AI briefings summarize governed state but may still require human review.
• Research and shadow results do not automatically become production controls.
• No model can remove tail risk.
• Abstention can be costly as well as protective.
• The governed AI-briefing artifact is not currently materialized; the operational LLM route is not active.
• Model-change auditing has a reader but no governed ledger artifact yet.
• Artifact retention and quarantine policy is descriptive and not enforced by an automated state machine.

16. Public Mathematical Glossary

Symbols introduced in this specification and their live status. Implementation status is one of LIVE, LIVE labeling, SHADOW, DIAGNOSTIC, or RESEARCH.

References